home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 401-425 / disk_408 / post / postlib.doc < prev    next >
Text File  |  1992-05-06  |  9KB  |  221 lines
  1. PostScript shared library interface (post.library, with Post V1.3)
  2. ==================================================================
  3.  
  4. Copyright Adrian Aylward 1990.
  5.  
  6. Free use and non-commercial reproduction of the binaries of the interpreter
  7. library (post.library) is permitted, providing that the copyright notices
  8. are not removed.  Distribution by disk libraries is permitted provided only
  9. a nominal copying fee is charged.
  10.  
  11. All other rights are reserved.
  12.  
  13. Introduction
  14. ============
  15.  
  16. The file "post.library" is an Exec library containing the PostScript
  17. interpreter.  It is designed to be shareable between different processes,
  18. supporting arbitrarily many PostScript activations - at least until you
  19. run out of memory.
  20.  
  21. This file should be read in conjunction with the header file "postlib.h".
  22.  
  23. The standard user interface source files are distributed with Post.  Read
  24. them as examples.
  25.  
  26. Activation Records
  27. ==================
  28.  
  29. Simultaneous multiple activations of PostScript are allowed.  Before using
  30. post.library you must first open it by a call to OpenLibrary.  To create
  31. an activation you then call PScreateact which returns a pointer to the
  32. activation record.  You can then make calls to the interpreter library,
  33. passing the activation record pointer as an argument.  You can create
  34. several activations, possibly from different processes and intermingle
  35. the interpreter calls if you wish.  When you have finished with an
  36. activation, call PSdeleteact to delete it and free the memory it used.
  37. When you have finished with the library call CloseLibrary; if no other
  38. processes have it open, then Exec can remove it from memory if the space
  39. is needed.  (N.B. if the space is not needed, the library will remain in
  40. memory in case it is opened again.)
  41.  
  42. N.B. the library can only be called from a process, as it calls various
  43. AmigaDOS functions.  It should be possible to pass activation records
  44. between processes (I think) but I have not tested it.
  45.  
  46. The Parameter Block
  47. ===================
  48.  
  49. The parameter block is the argument to PScreateact.  It is specifies the
  50. addresses of the bitmap planes, size of the page, and the amount of memory
  51. to be allocated for the activation etc..  Its format is defined in the
  52. header file.
  53.  
  54. N.B. all ints are 32 bits, shorts are 16 bits.
  55.  
  56. The page size is limited to 30000 pixels.  The densities (pixels per inch)
  57. may be any strictly positive integer value.  The y direction may be set
  58. to +1 - if the bitmap rows are in PostScript order (bottom row first) or
  59. -1 - Amiga order (top row first).
  60.  
  61.     page.buf[24]        Bitplane pointers, up to 24
  62.     page.len            Size in bytes of each plane
  63.     page.depth          Number of planes (must be 1,3,4)
  64.     page.reserved       Reserved, must be zero
  65.     page.xbytes         Number of bytes in each row
  66.     page.xsize          Number of pixels in each row
  67.     page.ysize          Number of rows
  68.     page.ybase          Base of current band
  69.     page.yheight        Total height of full page, for band rendering
  70.     page.xden           X density
  71.     page.yden           Y density
  72.     page.ydir           Y direction
  73.  
  74. As a starting point for memory sizes try the values following.  If you load
  75. many fonts you will need to increase the size of the VM.  The other sizes
  76. should prove adequate for even the more complex programs.
  77.  
  78.     memvlen    280000   VM
  79.     memflen     60000   Font cache
  80.     memllen     60000   Path lines
  81.     memhlen     20000   Halftones
  82.  
  83. The user data pointer is intended to be used to identify multiple
  84. activations.  You can set it to any value you like.  The function pointers
  85. are described below.
  86.  
  87.     userdata            User data pointer
  88.     flushfunc           Flush page function pointer
  89.     copyfunc            Copy page function pointer
  90.  
  91. The standard input and output streams are the DOS file handles to be used
  92. by the interpreter for %stdin, %stdout, %stderr.  Also the standard output
  93. is used for prompts and the error output for error messages.
  94.  
  95.     infh                Standard Input file handle
  96.     outfh               Standard Output file handle
  97.     errfh               Standard Error file handle
  98.  
  99. The rest of the block is reserved and must be set to zero.
  100.  
  101. Function Pointers
  102. =================
  103.  
  104. There are two function pointers within the parameter block, which are used
  105. when the interpreter needs to call routines supplied by its client.  If
  106. the pointers are zero the calls are skipped.
  107.  
  108. To help identify calls from multiple activations, the activation record
  109. address is also passed in a0 and the userdata pointer in a1.
  110.  
  111.       flushfunc(d0: int y1, d1: int y2)
  112.  
  113. Flush the bitmap to the screen.  The interpreter calls this function after
  114. a painting operation has updated the bitmap.  Then if the output is being
  115. viewed interactively the client can update the screen or window.  The
  116. arguments are the range of bitmap rows (y1 ... y2-1) that may have been
  117. updated.
  118.  
  119.       copyfunc(d0: int num)
  120.  
  121. Copy the page to the output device.  The argument is the value of #copies,
  122. which should be taken into account if the output is to a printer, but is
  123. not meaningful for screen output.
  124.  
  125. Library Entry points
  126. ====================
  127.  
  128. Prototypes and pragmas for the entry points are defined in the header file.
  129.  
  130.   Create a PostScript activation
  131.  
  132.           d0:int arec = PScreateact(a1:struct PSparm *parm)
  133.  
  134. The result is the address of the new activation record.  If the activation
  135. fails an error code is returned instead - zero if the interpreter failed
  136. to start at all because there was insufficient free memory, or an
  137. interpreter error code if there was an error during initialisation.
  138. Otherwise the result is the address of the activation record.  The result
  139. is always returned as an int.  If is is greater than errmax then the
  140. activation was successful, and the value is an address; otherwise the
  141. activation failed, and the result is zero or an error code.
  142.  
  143.   Delete a PostScript activation
  144.  
  145.           PSdeleteact(a0:APTR arec)
  146.  
  147. The activation record is deleted and the associated memory is freed.
  148.  
  149.   Interpret a string or file
  150.  
  151.           d0:int errnum = PSintstring(a0:APTR arec, a1:char *string,
  152.                                       d0:int length, d1:int flags)
  153.  
  154. If the flag PSFLAGSTRING is set, the contents of the string are interpreted
  155. as PostScript source.  If the flag PSFLAGFILE is set, the string is a file
  156. name, whose contents are interpreted.  If neither of these flag bits are set
  157. the string is ignored, but the other flag bits still have their effects; if
  158. both are set the result is undefined.
  159.  
  160. If PSFLAGINTER is set (when interpreting a file), the file is considered to
  161. be interactive.  The banner is printed, and the interpreter prompts for each
  162. line of input from the file.
  163.  
  164. If PSFLAGCLEAR is set, then after interpretation the operand stack is
  165. cleared and the dictionary stack is popped until only the system and user
  166. dictionaries remain.
  167.  
  168. If PSFLAGESAVE is set, the vm is saved before interpretation begins and
  169. restored afterwards.  You would normally use PSFLAGCLEAR with this option,
  170. to prevent invalidrestore errors.
  171.  
  172. If PSFLAGERASE is set, then the page is erased.  This happens right at the
  173. end, after any vm restore, so the page is erased taking into account the
  174. restored transfer function(s).
  175.  
  176.   Signal an interrupt
  177.  
  178.           PSsignalint(a0:APTR arec, d0:int flag)
  179.  
  180. This routine may be called to set (flag = 1) or clear (flag =0) the
  181. interrupt signal flag.  The interpreter tests this flag at the head of its
  182. main loop, and also within certain potentially length operators (=, ==,
  183. stack and pstack).  If the flag is set it generates an interrupt error.
  184. You may safely call this routine at any time during the like of the
  185. activation.  It is intended to be called from within your task's
  186. exception handler, if the CTRL/C break signal is set.
  187.  
  188.   Signal a floating point error
  189.  
  190.           PSsignalfpe(a0:APTR arec)
  191.  
  192. This routine is intended to be called whenever a floating point trap is
  193. generated by the interpreter.  It generates an immediate undefinedresult
  194. error.  You must not call it at any other time; if you do you will crash
  195. the machine.  It is only useful if you are using the version of the library
  196. compiled for the 68881 FPU or compatible chips.  (The software floating
  197. point routines do not generate traps).  Before calling the library you
  198. should set up a trap handler and set the bits in the fpcr register to
  199. enable the traps.  (If you do not set up the traps, the FPU will substitute
  200. the special value not-a-number for the result and continue.  The
  201. undefinedresult error will not be triggered, and results of your program
  202. may be incorrect.)  If you application does not use the FPU you can simply
  203. direct all traps to the library, otherwise it is essential that you
  204. ensure that you only call this routine if the trap derived from the library
  205. and not your own code.
  206.  
  207.   Error
  208.  
  209.           PSerror(a0:APTR arec, d0:int errnum)
  210.  
  211. This routine is intended to be called from within your own flush or copy
  212. page functions, to signal that an error ocurred.  You must not call it at
  213. any other time; if you do you will crash the machine.  The values for the
  214. error number are defined in the header file.
  215.  
  216. Versions
  217. ========
  218.  
  219. The version distributed with Post V1.3 has version number 1, revision 3.
  220.  
  221.